docs: onboarding polish — tutorial lesson-01 + audience router + STATE.a2ml refresh#649
Merged
Merged
Conversation
…a2ml refresh Three small wind-down items (larger consolidation tracked in #647): 1. docs/tutorial/lesson-01-hello.adoc — the docs/tutorial track started at lesson-02 (the intro lived only under docs/guides/). Adds a concise, self-contained first lesson with a lessons 1–10 map. Example verified against the built compiler: the `fn main` hello-world passes check/eval/compile (the bare top-level println form that guides/lessons/01 shows is a parse error on the current compiler — folded into #647). 2. README.adoc + docs/NAVIGATION.adoc — a top-level "Start here — by audience" router (new users / developers / maintainers), each pointing at existing entry points. Also adds a SOUNDNESS.adoc back-link in NAVIGATION. 3. .machine_readable/6a2/STATE.a2ml — 2026-06-21 session note + last-updated bump (it was self-flagged stale; still MIRRORS, does not lead). Guards green: check-doc-truthing, check-soundness-ledger, check-capability-anchors. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Lz7pRcec2Z3tVtaAhvB3M8
🔍 Hypatia Security ScanFindings: 41 issues detected
View findings[
{
"reason": "Action denoland/setup-deno@v2 needs attention",
"type": "unpinned_action",
"file": "publish-jsr.yml",
"action": "pin_sha",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Issue in instant-sync.yml",
"type": "secret_action_without_presence_gate",
"file": "instant-sync.yml",
"action": "peter-evans/repository-dispatch",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "Shell execution -- validate input before passing to shell (1 occurrences, CWE-78)",
"type": "js_exec_sync",
"file": "/home/runner/work/affinescript/affinescript/packages/affinescript-cli/mod.js",
"action": "flag",
"rule_module": "code_safety",
"severity": "high"
},
{
"reason": "Shell execution -- validate input before passing to shell (2 occurrences, CWE-78)",
"type": "js_exec_sync",
"file": "/home/runner/work/affinescript/affinescript/packages/affine-vscode/mod.js",
"action": "flag",
"rule_module": "code_safety",
"severity": "high"
},
{
"reason": "Shell execution -- validate input before passing to shell (1 occurrences, CWE-78)",
"type": "js_exec_sync",
"file": "/home/runner/work/affinescript/affinescript/affinescript-vite/src/affine-plugin-improved.js",
"action": "flag",
"rule_module": "code_safety",
"severity": "high"
},
{
"reason": "expect() in hot path (32 occurrences, CWE-754)",
"type": "expect_in_hot_path",
"file": "/home/runner/work/affinescript/affinescript/affinescriptiser/src/codegen/wasm_gen.rs",
"action": "flag",
"rule_module": "code_safety",
"severity": "medium"
},
{
"reason": "expect() in hot path (29 occurrences, CWE-754)",
"type": "expect_in_hot_path",
"file": "/home/runner/work/affinescript/affinescript/affinescriptiser/src/codegen/affine_gen.rs",
"action": "flag",
"rule_module": "code_safety",
"severity": "medium"
},
{
"reason": "unsafe block -- requires SAFETY comment (2 occurrences, CWE-676)",
"type": "unsafe_block",
"file": "/home/runner/work/affinescript/affinescript/runtime/src/panic.rs",
"action": "flag",
"rule_module": "code_safety",
"severity": "medium"
},
{
"reason": "unsafe block -- requires SAFETY comment (1 occurrences, CWE-676)",
"type": "unsafe_block",
"file": "/home/runner/work/affinescript/affinescript/runtime/src/alloc.rs",
"action": "flag",
"rule_module": "code_safety",
"severity": "medium"
},
{
"reason": "unsafe block -- requires SAFETY comment (3 occurrences, CWE-676)",
"type": "unsafe_block",
"file": "/home/runner/work/affinescript/affinescript/runtime/src/ffi.rs",
"action": "flag",
"rule_module": "code_safety",
"severity": "medium"
}
]Powered by Hypatia Neurosymbolic CI/CD Intelligence |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The three quick wind-down items from the close-out triage. The larger docs consolidation (unifying the two learning tracks, wiki-sync audit) stays tracked in #647.
1.
docs/tutorial/lesson-01-hello.adoc(new)The
docs/tutorial/track started at lesson-02 — the intro lived only underdocs/guides/, so a reader opening the tutorial began at lesson 2. Adds a concise, self-contained first lesson with a lessons 1–10 map and thecheck/eval/compileworkflow.The hello-world is verified against the built compiler:
fn main() -> Int { println(…); return 0; }passescheck, prints undereval, andcompiles to WASM. (Note: the bare top-levelprintln(…)form shown indocs/guides/lessons/01-hello-affinescript.adocis a parse error on the current compiler — folded into #647 rather than fixed here.)2. README + NAVIGATION — "Start here — by audience"
A top-level router so each audience has a clear entry point:
wiki/compiler/architecture→ ADRs → capability matrixMAINTAINERS→ contributing → ops playbook → soundness ledger(Also adds a
SOUNDNESS.adocback-link inNAVIGATION.adoc.)3.
.machine_readable/6a2/STATE.a2mlAdds a
2026-06-21session note (release fix #641, the already-landed #602 ctor fix, filed gaps #642–#644/#646/#647) and bumpslast-updated. It was self-flagged stale; it still mirrors the authoritative docs, it does not lead.Verification
All three doc guards pass locally:
check-doc-truthing,check-soundness-ledger,check-capability-anchors. No over-claim phrases introduced; no compiler/code changes.🤖 Generated with Claude Code
https://claude.ai/code/session_01Lz7pRcec2Z3tVtaAhvB3M8
Generated by Claude Code